<!DOCTYPE doctype PUBLIC "-//W3C//DTD HTML 4.0 Frameset//EN">

<HTML>
  <HEAD>
    <META name="generator" content=
    "HTML Tidy for Java (vers. 2009-12-01), see jtidy.sourceforge.net">

    <TITLE>Debugger Launchers: GDB</TITLE>
    <META http-equiv="Content-Type" content="text/html; charset=windows-1252">
    <LINK rel="stylesheet" type="text/css" href="help/shared/DefaultStyle.css">
  </HEAD>

  <BODY lang="EN-US">
    <H1>Debugger Launchers: GDB</H1>

    <P>Integration with GDB is achieved using a Python-based plugin for GDB. It is well-suited for
    debuging Linux user-space targets, many embedded systems, and sometimes Windows user-space
    targets. Please note you may need to obtain a properly-configured build of GDB for your target.
    If you are working with an embedded system, it is probably safest to install the "multiarch"
    build of GDB from your package manager.</P>

    <P>The following launchers based on GDB (GNU Debugger) are included out of the box:</P>

    <H2><A name="local"></A>Local</H2>

    <P>The plain "<TT>gdb</TT>" launch script defaults to launching the current program as a
    user-mode process on the local system. If there is no current program, or if you clear the
    <B>Image</B> option, this launcher will only start <TT>gdb</TT> and get it connected to a
    Ghidra trace. You may then manually start or connect to your target. Note that this may also
    require manual mapping of your program database(s) to the target memory.</P>

    <H3><A name="setup"></A>Setup</H3>

    <P>You must have GDB installed on the local system, and it must embed the Python 3 interpreter.
    If you have access to PyPI, setting up your Python 3 environment is done using Pip. Please note
    the version specifier for Protobuf.</P>

    <UL style="list-style-type: none">
      <LI>
<PRE>
python3 -m pip install psutil protobuf==3.20.3
</PRE>
      </LI>
    </UL>

    <P>If you are offline, or would like to use our provided packages, we still use Pip, but with a
    more complicated invocation:</P>

    <UL style="list-style-type: none">
      <LI>
<PRE>
cd /path/to/ghidra_<EM>
version</EM>/Ghidra/Debug
python3 -m pip install --no-index -f Debugger-rmi-trace/pypkg/dist -f Debugger-agent-gdb/pypkg/dist psutil protobuf
</PRE>
      </LI>
    </UL>

    <P>Beware that GDB may embed a different Python interpreter than your system's default. If you
    are still getting import errors, check the version that GDB embeds:</P>

    <UL style="list-style-type: none">
      <LI>
<PRE>
(bash)$ gdb
(gdb) python-interactive
&gt;&gt;&gt; import sys
&gt;&gt;&gt; sys.version
</PRE>
      </LI>
    </UL>

    <P>Note the version and ensure that you are invoking Pip with that version. Supposing
    <TT>sys.version</TT> indicates 3.10, you should invoke Pip using <TT>python3.10 -m
    pip</TT>.</P>

    <P><B>Warning</B>: Modern Linux distributions are beginning to adopt PEP 668, which prevents
    installation of Python packages outside of a virtual environment (venv) <EM>even for non-root
    user accounts</EM>. Unfortunately, <TT>gdb</TT> does not seem to honor the currently activated
    venv, and so such configurations are not officially supported. You may be able to work around
    this by modifying the <TT>PYTHONPATH</TT> lines of the launcher script, but your mileage may
    vary. For now, we recommend using the <TT>--break-system-packages</TT> argument with Pip.</P>

    <H3>Options</H3>

    <DIV class="image">
      <IMG alt="" src="images/GdbLauncher.png">
    </DIV>

    <UL>
      <LI><B>Image</B>: This is the path to the target binary image (ELF). Ghidra will try to fill
      this in based on information gathered when the current program was imported. If the file
      exists and is executable on the local machine, it will be filled in automatically. Otherwise,
      it is up to you to locate it. <B>NOTE:</B> If you have patched the current program database,
      these changes are <EM>not</EM> applied to the target. You can either 1) apply the same
      patches to the target once it is running, or 2) export a patched copy of your image and
      direct this launcher to run it.</LI>

      <LI><B>Arguments</B>: These are the command-line arguments to pass into the target process.
      These are passed as is to GDB's "<TT>set args ...</TT>" command.</LI>

      <LI><B><TT>gdb</TT> command</B>: This is the command or path to GDB. We recommend version 13
      or later. We require version 8 or later.</LI>

      <LI><B>Run command</B>: This is the GDB command to actually launch the target. In most cases
      this should be "<TT>starti,</TT>" since this will assure you an initial break and a chance to
      enable your breakpoints.</LI>

      <LI><B>Inferior TTY</B>: Depending on your target and/or personal preference, you may opt to
      separate the debugger's and the target's I/O. If you check this box, the launcher will use
      GDB's "<TT>set inferior-tty ...</TT>" command to direct the target's I/O to a second Terminal
      window.</LI>
    </UL>

    <P>Once running, you are presented with GDB's command-line interface in Ghidra's Terminal. This
    is the <EM>bona fide</EM> GDB command-line interface, so it has all the functionality you would
    expect. If you command GDB from this shell, the plugin will keep Ghidra in sync. The terminal
    can also be used to interact with the target application when it is running. The plugin
    provides an additional set of commands for managing the connection to Ghidra, as well as
    controlling trace synchronization. These are all in the "<TT>ghidra</TT>" command prefix. You
    can use tab completion to enumerate the available commands and GDB's "<TT>help</TT>" command to
    examine their documentation.</P>

    <H2><A name="ssh"></A>Via SSH</H2>

    <P>This works the same as the GDB launcher, but runs <TT>gdb</TT> on a remote system via
    <TT>ssh</TT>. In contrast to the previous system, which used an SSH library for Java, this
    launcher uses the <TT>ssh</TT> command on the local system. Thus, it should have broader
    compatibility with remote systems, and it should use the same configuration files as you are
    accustomed to. That said, we developed it using OpenSSH, so your experience will be best if
    your copy understands the same command-line arguments.</P>

    <H3>Setup</H3>

    <P>You must install GDB and an SSH server onto the target host. Your local SSH client must
    support remote port forwarding (-R option) and terminal allocation (<TT>-t</TT> option), and
    the remote server must be configured to permit them.</P>

    <P>You will need to manually install the required Python packages on the <EM>target</EM> host,
    comprising our plugin for GDB and its dependencies. Copy all of the Python packages from
    <TT>Ghidra/Debug/Debugger-rmi-trace/pypkg/dist/</TT> and
    <TT>Ghidra/Debug/Debugger-agent-gdb/pypkg/dist/</TT> to the remote system. It is easiest to put
    them all in one directory, e.g., <TT>~/ghidra-pypgk/</TT>. Then install them:</P>

    <UL style="list-style-type: none">
      <LI>
<PRE>
python3 -m pip install --no-index -f ~/ghidra-pypkg/ ghidragdb
</PRE>
      </LI>
    </UL>

    <P>Please see <A href="#setup">Setup</A> for notes about embedded Python interpreter
    versions.</P>

    <H3>Options</H3>

    <UL>
      <LI><B>Image</B>: This is the path to the target binary image (ELF) <EM>on the remote
      system</EM>. Ghidra will try to fill this in based on information gathered when the current
      program was imported; however, it cannot examine the <EM>remote</EM> system. If the file
      exists and is executable on the <EM>local</EM> machine, it will be filled in automatically.
      Whether or not it is filled automatically, please ensure the location is correct with respect
      to the remote system. <B>NOTE:</B> If you have patched the current program database, these
      changes are <EM>not</EM> applied to the target. You can either 1) apply the same patches to
      the target once it is running, or 2) export a patched copy of your image, copy it to the
      target system, and direct this launcher to run it.</LI>

      <LI><B>Arguments</B>: This works the same as in GDB.</LI>

      <LI><B>[User@]Host</B>: This is the host name of the target system, optionally including a
      user name. This is passed as is to <TT>ssh</TT>, which may interpret it according to local
      configuration.</LI>

      <LI><B>Remote Trace RMI Port</B>: An available TCP port on the target system, which will
      listen for GDB's Trace RMI connection and forward it back to Ghidra.</LI>

      <LI><B>Extra <TT>ssh</TT> arguments</B>: These are extra arguments to pass to <TT>ssh</TT>.
      They are inserted immediately after the <TT>ssh</TT> command but before the host name. Beware
      that syntax errors may cause strange behavior, and that not all features may be compatible
      with this launcher.</LI>

      <LI><B><TT>gdb</TT> command</B>: This works the same as in GDB, but with respect to the
      <EM>remote</EM> file system.</LI>

      <LI><B>Run command</B>: This works the same as in GDB.</LI>

      <LI>Note there is no option to create a second Terminal (TTY) for the target.</LI>
    </UL>

    <H2><A name="gdbserver_ssh"></A><TT>gdbserver</TT> via SSH</H2>

    <P>This works similarly to the GDB via SSH launcher, but instead of tunneling the Trace RMI
    connection, tunnels the RSP (<TT>gdbserver</TT>) connection. There is actually a fairly elegant
    method of doing this straight from within <TT>gdb</TT>, which is exactly what this launcher
    does:</P>

    <UL style="list-style-type: none">
      <LI>
<PRE>
target remote | ssh user@host gdbserver - /path/to/image
</PRE>
      </LI>
    </UL>

    <P>This has some advantages compared to running <TT>gdb</TT> on the remote target:</P>

    <OL>
      <LI>GDB may not be available on the remote target.</LI>

      <LI>There is no need to install our plugin for GDB on the target.</LI>
    </OL>

    <P>But, it also has some drawbacks:</P>

    <OL>
      <LI><TT>gdbserver</TT> must be installed on the remote system, and the local <TT>gdb</TT>
      must be compatible with it.</LI>

      <LI>It may be slightly more annoying to map modules from the remote system, because of the
      way GDB reports these modules.</LI>

      <LI>The memory map may be absent. Though this is overcome by creating an entry for the entire
      address space, if the map is of interest to your analysis, it may not be available.</LI>
    </OL>

    <H3>Setup</H3>

    <P>You must have GDB installed on the local system and a compatible version of
    <TT>gdbserver</TT> installed on the target system. You must have an SSH server installed on the
    target system. It may be worth testing your setup manually (outside of Ghidra) to ensure
    everything is configured correctly. On the local system, follow the steps given in <A href=
    "#setup">Setup</A>. There are no additional Python requirements on the target system.</P>

    <H3>Options</H3>

    <UL>
      <LI><B>Image</B>: This works the same as in GDB via SSH.</LI>

      <LI><B>Arguments</B>: This works the same as in GDB.</LI>

      <LI><B>[User@]Host</B>: This works the same as in GDB via SSH.</LI>

      <LI><B>Remote Trace RMI Port</B>: An available TCP port on the target system, which will
      listen for GDB's Trace RMI connection and forward it back to Ghidra.</LI>

      <LI><B>Extra <TT>ssh</TT> arguments</B>: This works the same as in GDB via SSH.</LI>

      <LI><B><TT>gdbserver</TT> command</B>: This is the command or path to <TT>gdbserver</TT> with
      respect to the <EM>remote</EM> file system.</LI>

      <LI><B>Extra <TT>gdbserver</TT> arguments</B>: These are extra arguments to pass to
      <TT>gdbserver</TT>. They are inserted immediately after <TT>gdbserver</TT> but before the
      dash. Beware that syntax errors may cause strange behavior, and that not all features may be
      compatible with this launcher.</LI>

      <LI><B><TT>gdb</TT> command</B>: This works the same as in GDB, with respect to the
      <EM>local</EM> file system.</LI>

      <LI>Note there is no option to create a second Terminal (TTY) for the target.</LI>
    </UL>

    <H2><A name="qemu"></A>QEMU</H2>

    <P>These launchers orchestrate a QEMU user- or system-mode target and connect to it using our
    Python plugin for GDB. Ghidra will inspect the current program and attempt to map its language
    to the appropriate QEMU command, but due to subtle errors and/or outright failure, the default
    value for the <B>QEMU command</B> option often requires careful inspection.</P>

    <P>There are two separate scripts for QEMU, one for user mode and one for system mode. Note
    that QEMU does not support user-mode emulation on Windows, so that script is not available on
    Windows hosts.</P>

    <H3>Setup</H3>

    <P>You must acquire versions of QEMU and GDB that support the target architecture. Aside from
    the copy of QEMU required, setup is the same whether for user or system mode. As for GDB, on
    many distributions of Linux, you can install <TT>gdb-multiarch</TT>. Follow the steps given in
    <A href="#setup">Setup</A>.</P>

    <H3>Options</H3>

    <UL>
      <LI><B>Image</B>: This is the path to the target binary image (ELF). This works the same as
      in GDB, but is passed to QEMU. This will also provide the name to GDB using its "<TT>file
      ...</TT>" command.</LI>

      <LI><B>Arguments</B> (User-mode only): These are the command-line arguments to pass into the
      target process. These are passed as is on QEMU's command line.</LI>

      <LI><B>QEMU command</B>: The command or path to QEMU.</LI>

      <LI><B>QEMU Port</B>: An available TCP port for QEMU to listen on for GDB.</LI>

      <LI><B>Extra <TT>qemu</TT> arguments</B>: Extra arguments to pass to <TT>qemu</TT> or
      <TT>qemu-system</TT>. These are inserted immediately after the <TT>qemu</TT> command but
      before the target image. Run <TT>qemu<EM>[-system]-arch</EM> --help</TT> to see the options
      supported. Beware that syntax errors may cause strange behavior, and that not all QEMU
      features may be compatible with Ghidra.</LI>

      <LI><B><TT>gdb</TT> command</B>: This works the same as in GDB, but defaults to
      "gdb-multiarch."</LI>

      <LI><B>QEMU TTY</B>: This works similarly as in GDB, but just runs QEMU in the second
      Terminal window.</LI>

      <LI><B>Pull all section mappings</B>: For some targets the memory mappings cannot be
      correctly conveyed to Ghidra module by module. This setting forces GDB to send the
      <EM>section</EM> mappings to Ghidra. <B>Warning</B>: This operation is expensive for large
      targets, so it should only be enabled if required (e.g. unable to correctly place
      breakpoints). <A href=
      "help/topics/DebuggerModulesPlugin/DebuggerModulesPlugin.html#auto_map">Auto-Map</A> by
      Section is required when this option is enabled, or else address translation may
      <EM>still</EM> be incorrect.</LI>
    </UL>

    <H2><A name="wine"></A>Wine</H2>

    <P>This launchers runs <TT>wine</TT> in a <TT>gdb</TT> session on Linux and directs it to a
    target Windows executable. There are other ways to rig a Windows target in GDB on Linux, but
    this is the method we have chosen. This may prevent GDB from processing the object file,
    because it is a PE file, and most copies of GDB for UNIX will support only ELF. Nevertheless,
    Ghidra should recognize the target and map it, giving you symbols and debug info in the front
    end, even if not in the GDB CLI.</P>

    <H3>Setup</H3>

    <P>In addition to the steps given in <A href="#setup">Setup</A>, you must install Wine on your
    system. Prepare for configuration by locating the actual <TT>wine</TT> executable. These are
    often in some library directory and named "<TT>wine32</TT>" or "<TT>wine64</TT>." To find them,
    either examine the file list of the installed package, or dissect the wrapper <TT>wine</TT>
    script, usually on your path:</P>

    <UL style="list-style-type: none">
      <LI>
<PRE>
less $(which wine)
</PRE>
      </LI>
    </UL>

    <P>The locations are usually given in variables at the top of the script, e.g.,
    "<TT>/usr/lib/wine/wine64</TT>". One is for 64-bit Windows targets and another is for 32-bit
    Windows targets. Unlike native Windows, Wine does not (yet) implement WoW64 (Windows on Windows
    64). Instead, the 32-bit target is loaded using a 32-bit copy of Wine, and so is serviced by
    Linux's 32-bit system calls. <FONT color="red"><B>NOTE:</B> Careful attention must be given to
    select the correct <TT>wine</TT> executable for the target program's architecture!</FONT> Even
    though the <TT>wine</TT> executable is smart enough to correct this mistake, it results in
    calls to <TT>exec</TT>, which confuse this launcher. If GDB complains that it cannot place
    breakpoints because of memory access, it is probably because of this mistake.</P>

    <P>The launcher loads some additional support packages in our plugin for GDB, e.g., to scan the
    memory map for PE files and amend the module list. Thus, Ghidra can display both Windows and
    Linux modules, and map them to its program databases accordingly, despite GDB's inability to
    process PE files. There are perhaps other configurations of GDB for Linux that can process ELFs
    as well as PEs loaded by Wine, but they do not seem to be readily available in any popular
    package repositories.</P>

    <H3>Options</H3>

    <UL>
      <LI><B>Image</B>: This is the path to the target binary image (EXE). This works the same as
      in GDB, but is passed to Wine via GDB's "<TT>set args ...</TT>". This will also provide the
      name to GDB using its "<TT>file ...</TT>" command.</LI>

      <LI><B>Arguments</B>: These are the command-line arguments to pass into the target process.
      These are included in "<TT>set args ...</TT>".</LI>

      <LI><B>Path to <TT>wine</TT> binary</B>: The path to wine for your target architecture. <FONT
      color="red">See note above!</FONT></LI>

      <LI><B><TT>gdb</TT> command</B>: This works the same as in GDB.</LI>

      <LI><B>Inferior TTY</B>: This works the same as in GDB.</LI>
    </UL>

    <H2><A name="remote"></A>Remote</H2>

    <P>This launcher can target any TCP-based GDB stub that is compatible with a local copy of
    <TT>gdb</TT>. Essentially, it just starts <TT>gdb</TT> and then enters</P>

    <UL style="list-style-type: none">
      <LI>
<PRE>
target remote [host]:[port]
</PRE>
      </LI>
    </UL>

    <P>into it. It is best to test this command outside of Ghidra to be sure everything is
    compatible before using this launcher. This launcher does not require an image, nor does it
    create your target. Thus, it can be used without a current program.</P>

    <H3>Setup</H3>

    <P>On your local system, follow the steps given in <A href="#setup">Setup</A>. Your version of
    GDB must be compatible with the stub (e.g., <TT>gdbserver</TT>) on the target system. There are
    no additional requirements on the target system.</P>

    <P><B>NOTE:</B> The target program image must match that imported in Ghidra, or else things may
    not map or synchronize correctly.</P>

    <H3>Options</H3>

    <UL>
      <LI><B>Target</B>: The type of target. Either <TT>remote</TT> or <TT>remote-extended</TT>,
      depending on the capabilities of the stub.</LI>

      <LI><B>Host</B>: The host name of the target stub.</LI>

      <LI><B>Port</B>: The TCP port of the target stub.</LI>

      <LI><B>Architecture</B> (optional): If the stub does not describe its architecture to GDB,
      you must set it before connecting. This is passed as is to "<TT>set arch ...</TT>"
      immediately before the "<TT>target ...</TT>" command. Enter "<TT>set arch</TT>" into a GDB
      session outside of Ghidra to see the list of available options in your configuration. You may
      want to use <TT>gdb-multiarch</TT>.</LI>

      <LI><B><TT>gdb</TT> command</B>: This works the same as in GDB, though you may want to use
      <TT>gdb-multiarch</TT>.</LI>
    </UL>

    <H2><A name="rr"></A>rr</H2>

    <P>This launcher runs <TT>rr</TT> in a <TT>gdb</TT> session on Linux for replaying rr-generated
    traces.</P>

    <H3>Options</H3>

    <UL>
      <LI><B>Trace Dir</B>: This is the path to the trace directory, stored by default in the
      user's home directory in <TT>.local/share/rr/target_name</TT>.</LI>

      <LI><B><TT>rr</TT> command</B>: This is the command or path to <TT>rr</TT>.</LI>
    </UL>

    <P>Other options are the same as in GDB.</P>
  </BODY>
</HTML>
